PsL Monthly 1993 December/PSL Monthly Shareware CD-ROM (December 1993).iso/prgmming/dos/pascal/tgraph.com/TGRAPH.DOC

Text File | 1991-01-04 | 23.4 KB | 570 lines

------------------------------------------------------------------------------
                           TGRAPH  Release 3.1
------------------------------------------------------------------------------


TGRAPH -- Full access to the Tandy 1000's extra graphics modes with
          TurboPascal versions 4.0, 5.0, 5.5, or 6.0.


Why the TGRAPH package?

        The Tandy 1000 has greater graphics capabilities than the other
members of the IBM PC compatible family.  It alone supports 160x200
16-color, 320x200 16-color, and 640x200 4-color graphics schemes.  BIOS
calls those three extra video modes 8, 9, and 10 respectively.

        Traditionally those extra modes have been accessible only from
one high-level language: the interpreted GW-BASIC supplied with the
computer.  BASIC calls those modes SCREEN 3, 5, and 6.

        TurboPascal, as it comes off the shelf, is blind to the fancy
color and graphics tricks the Tandy 1000 can perform.  These routines
in TGRAPH offer programmers easy access to Video Mode 9.  That's the
16-color, 320x200 screen which can be dazzling in a program.  (Much of
this material also will work in modes 8 and 10, but it has been
developed and tested primarily for mode 9.)


You MUST protect the screen memory area first:

        Though we'll discuss protecting screen memory in detail later,
in TP 4.0 or later just placing a compiler directive limiting the stack
and heap sizes at the top of your program will probably get you going
through all your early projects with TGRAPH.  Just do this at the top
of your program for now:

                   {$M 8000,0,0}

        That will set a smallish stack with no heap.  If your program
bombs, locks, or has distorted graphics images you'll need to consider
exactly what's happening up high in memory after reading the later
discussion.  And especially you'll need to study that if you are
allocating heap memory.


Will TGRAPH work on an EGA?

        Nope.  EGA screen memory is organized quite differently.  Even
though there are similar appearing video capabilities with an EGA, the
video modes are numbered dissimilarly and work differently.  That 'T'
in TGRAPH stands for Tandy 1000.


How to incorporate TGRAPH:

        With TurboPascal versions 4.0 or later, just specify TGRAPH40,
TGRAPH50, TGRAPH55, or TGRAPH60 in a USES statement depending on which
version of TurboPascal you're using.  The TGRAPHxx.TPU file of this
archive must be accessible to TurboPascal during compilation -- show
the appropriate path in Options/Directories/Units.


Here are TGRAPH's procedures and functions:

[Any reference to a color in these routines will accept integers 0 - 15
or TurboPascal's pre-defined constants such as Red, Blue, or LightCyan.
Those constants are defined in the Crt Unit.]

    Plot
        Syntax: Plot (X,Y,Color);

        Places a single pixel at the X, Y location in the specified
        Color.

    Draw
        Syntax: Draw (X1,Y1,X2,Y2,Color);

        Draws a line from the X1, Y1 starting point to X2, Y2 in the
        specified Color.

    Circle
        Syntax: Circle (X,Y,Radius,Color);

        Draws a circle in the specified Color with its center at X, Y
        using the specified Radius.

    GetPic
        Syntax: GetPic (Buffer,X1,Y1,X2,Y2);

        Copies the contents of a rectangular area defined by X1, Y1,
        X2, and Y2 into the variable Buffer.

        The Buffer should be defined as an array of byte.  Its minimum
        size can be calculated as follows:

              when Width  := abs(x1-x2)+1
               and Height := abs(y1-y2)+1

              then BufferSize :=  4+((Width +1) div 2)*Height

    PutPic
        Syntax: PutPic (Buffer,X,Y);

        Copies the contents of the variable Buffer onto a rectangular
        area of the screen.  X and Y define the upper left-hand corner
        of the picture area.  (Caution to TP3 users: that language
        used the lower left-hand corner.)  Buffer is a variable defined
        as an array of byte in which a picture has been previously
        stored by GetPic.

    PutPix
        Syntax: PutPix (Buffer,X,Y);

        An XOR version of PutPic, this can be is useful for two sorts
        of special effects.  You can erase an image by using PutPix to
        place a second copy at the same location already placed on the
        screen by PutPic.  That can be useful for animation effects.

        And you can blend or appear to overlay two images with each
        other.  It's easier to see how this works with some
        experimentation than to explain.

        A Brown pixel on the screen being XORed by a Cyan pixel in the
        PutPix image will result in a Magenta pixel being displayed:

                Brown    = 0110 binary  = 6 decimal
                Cyan     = 0011 binary  = 3 decimal
                        XOR
                Magenta  = 0101 binary  = 5 decimal

    PutDelay
        Syntax: PutDelay (Buffer,X,Y,Speed);

        Similar to PutPic except the speed of display is controlled by
        the integer Speed which may be between 1 and 9999.  1 will put
        the picture onto the screen just about as fast as the plain
        PutPic.  A value of 50 will fill a screen in about 6 seconds
        on a 4.7 mHz 8088 machine, and a value of 9999 takes forever.
        Be careful, a value of 0 is the same as 9999.

    SetCrtMode
        Syntax: SetCrtMode (Mode,ClearFlag);

        Sets video mode to that specified by the integer Mode and clears
        or does not clear the screen according to the boolean ClearFlag
        being either 'True' or 'False'.  If the ClearFlag is set false
        and the previous screen is incompatible with the requested
        mode, clearing will occur anyway.

        The applicable modes are:

         0:  Text     40x25 black and white
         1:  Text     40x25 color
         2:  Text     80x25 black and white
         3:  Text     80x25 color
         4:  Graphic  320x200 4-color graphics
         5:  Graphic  320x200 "gray" graphics on composite monitor
         6:  Graphic  640x200 "high resolution" black and white graphics
         --   -----
         8:  Graphic  160x200 16-color graphics
         9:  Graphic  320x200 16-color graphics
        10:  Graphic  640x200 4-color graphics

    GetCrtMode
        Syntax: GetCrtMode

        Integer function returns the present video mode.  A tidy use
        would be to call GetCrtMode upon entering the program, enter a
        graphics mode to do other processing, and then use SetCrtMode
        to return the mode to what it was before exiting.

        Example: StartingMode := GetCrtMode;

    GraphBorder
        Syntax: GraphBorder (Color);

        Sets the screen border to the specified Color.

    GraphBackground
        Syntax: GraphBackground (Color);

        Sets the entire screen, interior and border, to the specified
        Color.

    BorderBack
        Syntax: BorderBack (BorderColor,InteriorColor);

        Sets the interior and border of the screen to the specified
        colors.

    ClearScreen
        Syntax: ClearScreen;

        Clears the screen of all markings except the previously
        established border and interior colors.

    FillScreen
        Syntax: FillScreen (Color);

        This procedure differs from GraphBackground in that FillScreen
        always leaves the border black.  FillScreen colors the interior
        of the screen with the specified Color.

    Recolor
        Syntax: Recolor (Color1,Color2);

        Changes all instances of integer Color1 presently on screen to
        Color2.

    FillWindow
        Syntax: FillWindow (X1,Y1,X2,Y2,Color);

        Fills a rectangular area of the screen defined by the integer
        coordinates with integer color.

    CheckForTandy
        Syntax: CheckForTandy

        Boolean function searches BIOS-ROM for 'andy' or 'ANDY'.  Used
        for attempting to ascertain if there is a Tandy copyright which
        would give some assurance that a program is about to be run on
        a Tandy 1000.  Obviously, Tandy 1200s, 2000s, 3000s, and 4000s
        will also contain that string.  Returns 'True' if string found.

        Example:  If CheckForTandy = true then ...

    Paint
        Syntax: Paint (X,Y,FillColor,BorderColor)

        Starting at the X, Y location fills an area delimited by
        BorderColor with FillColor.


Identifying a Tandy 1000

        In my own Tandy 1000 graphics programming I've always thought
it important to make certain the user really is running the program on
a Tandy 1000.  Any Video Mode 9 program sure is going to be weird on
the rest of the IBM PC compatibles.  It won't break anything, but
neither will the graphics screens display.

        Tandy has previously been awfully close-mouthed about any
unique signature byte any place in ROM so my identification schemes
have been built on several checks.

        First I use the CheckForTandy function above.

        Next, the byte in BIOS ROM at Mem[$F000:$FFFE] can help
identify the machine.  An $FD there positively identifies an IBM PCjr.
An $FF indicates an IBM PC or compatible -- the Tandy 1000 will have
$FF.  (And Tandy 2000s will be weeded out by a $00.  Perhaps 3000s and
4000s are not $FF, I haven't been able to test.  An IBM PC XT has $FE
and an IBM PC AT has $FC there.  If all their clones follow that
scheme, you will rule them out easily.)

        If both those tests pass, then I have looked at the DOS
equipment list for total memory available to see if it reports 16K
less than you'd expect.  That is, has the 16K taken by the screen
memory been subtracted from 128, 256, 384, 512, or 640K.  Specifically,
see if the byte at Mem[$0040:$0013] is either $70 or $F0.

        A Tandy 1000 TL though may be configured with up to 64k used
for multiple pages of video memory, and that same machine might have
add-on dedicated video memory giving 128k for video memory.  It, and
any later members of the Tandy 1000 family using the same scheme, will
slip through the above described sequence.

        In my own Tandy 1000 graphics programming, I have previously
done the above checking sequence, but then, if I can't positively
identify a Tandy 1000, have given the user a chance to insist that the
machine is, in fact, a Tandy 1000.

        Bryan Headley, a Tandy staffer providing vendor development
support on CompuServe, in May 1989, suggested another check sequence,
presumably speaking officially for Tandy though they certainly had been
tight about it previously.

        He says first check for EGA, VGA, Hercules, etc.  If these all
fail then assume this is a CGA.  He doesn't say how to do that check,
and the only method I know of would be to use TP's DetectGraph function
from its Graph unit.  I have no idea what it is really looking for.

        Having ruled out the other sorts of video displays, he says
next check that Mem[$F000:$FEEE]=$FF -- that's the Machine ID byte
we've discussed earlier.

        And finally then check for Mem[$F000:$C000]=$21 which is a
unique signature byte for Tandy 1000s if the machine is first
determined to be a CGA and the Machine ID is $FF.

        My most recent programming goes in for overkill by doing all of
these things with a Tandy1000 boolean function like this:

     Function Tandy1000 : boolean;
     begin

     Tandy1000 := true;    {Initialize the function as true.  Both
                            the check sequences below exit if
                            successful and the function gets defined
                            false only if they fail.}

     If     (Mem[$F000:$FFFE] = $FF)
        and (CheckForTandy)
        and (((Mem[$0040:$0013]=$70) or (Mem[$0040:$0013]=$F0)))
     then exit

     Else begin
     DetectGraph(GrDriver,GrMode);
     If     (GrDriver=CGA)
        and (Mem[$F000:$FEEE] = $FF)
        and (Mem[$F000:$C000] = $21)
     then exit;
     end;

     Tandy1000:=false;
     end;


More on protecting screen memory:

        The usual Tandy 1000, in any of the 'normal' video modes below
9, uses the top 16K of installed RAM for screen memory.  That address
varies according to how much memory you have installed, but BIOS then
does a trick to call that address $B800 as the start of the screen
memory area regardless of how many memory chips are present.

        When using video modes 9 or 10 you need 32K at the top of
RAM for screen memory.  BIOS is still going to address it as $B800, but
the true address will now be 32K below the top of installed RAM.

        BIOS-ROM automatically protects the top 16K of the Tandy 1000
from being overwritten by anything.  But there is no automatic
protection for the next 16K when you are using one of the video modes
needing a total of 32K.  You've got to do that yourself.  And if you
don't do so, any program using Video Mode 9 may crash dead requiring
you to punch the Big Orange Button.

        With TP3 it was especially tricky protecting that top 32k of
memory since that language version would generally attempt to build its
stack downward from the highest RAM location DOS told it was available.
That was right in the middle of our screen memory and every single
program got clobbered without some trickery.

        (This present incarnation of TGRAPH no longer supports TP3
though earlier versions did.  If you are using TP3 you'll want to write
me directly for a copy of an earlier TGRAPH version which includes the
necessary files.  dpg)

        TP4, TP5, TP55, and TP6 all default to beginning the stack 16k
above the top of the executable program.  In many situations that
would not be likely to damage the screen memory, but as a general rule
I'd urge you to declare a smaller stack.  That's what the {$M
8000,0,0} compiler directive discussed much earlier did to set about
an 8k stack.

        Then if you're using TP's heap for pointer structures you'll
need to limit it as precisely as possible.  The heap in these later
language versions by default will be started just above the stack and
will grow upwards to the maximum memory installed in the machine
possibly clobbering the screen memory.

        Calculate your heap requirements carefully and specify as small
a HeapMax in the {$M directive as possible.

        These methods of limiting memory will probably succeed for most
of the computer environments your program will be run in.  Remember
though that DOS has no way of officially knowing that all the top 32K
is forbidden territory.  In a multi-tasking situation, screen memory
may get clobbered.  In a machine with limited total RAM, or with much
of RAM filled up by resident programs, screen memory may get clobbered
even with small stack and heap allocations.

        Most of the time you'll be safe.  We're not talking about
physical damage to anything, just a program that locks up the system.

        I've always thought it classy to have the program calculate how
much memory is available above it and, prior to setting Video Mode 9,
refuse to run if it finds that the additional screen memory will be
damaged by the program.

        This AdequateMemory procedure is an approach I've used to doing
that.  It uses DOS function $48, Allocate Memory, to request an
impossibly large block of memory.  When DOS returns with an error, the
actual amount of memory available is in BX expressed in paragraphs.
You can check to see that it is at least 16384 bytes.

     Procedure AdequateMemory ;
     var Regs:registers;        {defined in the DOS unit}

     begin
        Regs.ah := $48;         { $48 -- attempt to Allocate Memory   }
        Regs.bx := $FFFF;       { at an impossibly high value.  Error }
        MsDos(Regs);            { will return available memory in BX  }

        if (Regs.bx * 16.0) < 16384.0 then
        begin
           writeln('Sorry.  Insufficient graphics memory.');
           writeln('You need ',16384 - (Regs.bx * 16),' bytes more.');
           halt;
        end;   { if Regs.bx }
     end;      { AdequateMemory }


Origins of TGRAPH:

        The TGRAPH routines except two have all been written in
assembly language by Joe Glockner who is primarily responsible for
developing the entire package.

        I, the author of this documentation, Don Phillip Gibson, had
written a MONOPOLY game which became immensely popular.  It used TP3's
standard CGA four-color graphics schemes.  Joe became entranced with
that game and was determined to get it adapted to his new Tandy 1000's
graphics capabilities.  At that time he knew zilch about TurboPascal
and absolutely nothing about assembly language.  But he knew he wanted
a sixteen-color MONOPOLY board!

        Joe began constructing sixteen-color boards in GW-BASIC and
they looked great, but interpreted BASIC would never be acceptable
running that game.  He taught himself TurboPascal to tinker around with
the game source files some more.

        William Harris, Cleveland, Ohio, in 1985 had written and made
available on CompuServe's BORPRO a group of TP3 procedures which made
access to video modes 9 and 10 possible.  He provided the necessary
capability with TP3 to protect an area of RAM for the additional screen
memory required, and to set the screen modes.  Using TurboPascal's
Intr() procedure, he constructed replacements for the usual Draw and
Plot type of necessities.

        I sent Joe a copy of Harris' graphics routines but patiently
tried to explain they simply would never do the job for the MONOPOLY
game without accompanying GetPic and PutPic routines.  I was getting a
little concerned about how I could get this fanatic off my game.

        And the next thing I knew, Joe had taught himself assembly
language and had constructed beautiful GetPic and PutPic routines in
assembly language for my use.  All of this within four months time!
That's two completely different programming languages he learned to
accomplish it.  I was overwhelmed.

        Joe didn't even stop there, but went ahead to develop the full
set of machine coded graphics procedures found in TGRAPH.

        The Draw routine used for the TP3 version of TGRAPH was Joe's
machine coded one, but it misbehaved mysteriously with TP4 and William
Harris' TurboPascal procedure now replaces it.  It turned out to be
just as fast and small.

        The Paint procedure added with TGRAPH v3.0 began as a machine
coded routine in the 'Bluebook of Assembly Language Routines for the
IBM PC & XT' by Christopher L. Morgan, The Waite Group, 1984.

        Joseph A. Albrecht of Belle Plain, Minnesota, another devotee
of Tandy 1000's graphics, adapted Morgan's Paint procedure to Video
Mode 9 and increased its speed tremendously so that it became a truly
usable tool.  It is with Albrecht's permission that I have adapted his
assembler code to be added to TGRAPH v3.0.

        (Albrecht has distributed the GRAFIX package of routines which
interface especially nicely with QuickBASIC but are also usable via
Intr() calls from TurboPascal or any language which can call an
interrupt.  GRAFIX requires installation of a memory resident library.)


This Stuff is Public Domain:

        These routines are placed into public domain for the use of
TurboPascal programmers working with the Tandy 1000.  Further
distribution is encouraged as long as it is done without charge for the
program material.


Original TGRAPH author:

                 Joe Glockner
                 915 Boone Drive
                 Sherman, TX 75090

TGRAPH.DOC and on-going support by:

                 Don Phillip Gibson
                 910 East 11th
                 Winfield, KS 67156

                 CompuServe: 75725,1752
                 GEnie: DGIBSON


Contents of the TGRAPH package:

        TGRAPH40.TPU   -  The unit for use with TurboPascal 4.0
        TGRAPH50.TPU   -  The unit for use with TurboPascal 5.0
        TGRAPH55.TPU   -  The unit for use with TurboPascal 5.5

        TGRAPH60.TPU   -  The unit for use with TurboPascal 6.0

        DEMO.PAS       -  Brief demonstration ready for compilation.

        TGRAPH.DOC     -  This file.


Revisions:

        1.0     Original release, supported only TurboPascal v3.+
                (August, 1987)

        2.0     Added the TPU support for TP4.  (December 18, 1987)

        2.1     Fixed a flaky bug in the Draw procedure which acted up
                only in TGRAPH40.TPU (new file dated Mar 27, 1988.)

        2.2     Added the TPU support for TP5.  (October 1, 1988)

        3.0     Added the Paint procedure and the TPU for TP55.
                Documentation revised and all TP3 material removed from
                the package.  (September 4, 1989)

        3.1     Added the TPU support for TP6.  (January 4, 1991)


         ----------------end-of-author's-documentation---------------

                         Software Library Information:

                    This disk copy provided as a service of

                           Public (software) Library

         We are not the authors of this program, nor are we associated
         with the author in any way other than as a distributor of the
         program in accordance with the author's terms of distribution.

         Please direct shareware payments and specific questions about
         this program to the author of the program, whose name appears
         elsewhere in  this documentation. If you have trouble getting
         in touch with the author,  we will do whatever we can to help
         you with your questions. All programs have been tested and do
         run.  To report problems,  please use the form that is in the
         file PROBLEM.DOC on many of our disks or in other written for-
         mat with screen printouts, if possible.  PsL cannot debug pro-
         programs over the telephone, though we can answer questions.

         Disks in the PsL are updated  monthly,  so if you did not get
         this disk directly from the PsL, you should be aware that the
         files in this set may no longer be the current versions. Also,
         if you got this disk from another vendor and are having prob-
         lems,  be aware that  some files may have become corrupted or
         lost by that vendor. Get a current, working disk from PsL.

         For a copy of the latest monthly software library newsletter
         and a list of the 3,000+ disks in the library, call or write

                           Public (software) Library
                               P.O.Box 35705 - F
                            Houston, TX 77235-5705

                                 Orders only:
                                1-800-2424-PSL
                              MC/Visa/AmEx/Discover

                          Outside of U.S. or in Texas
                          or for general information,
                              Call 1-713-524-6394

                          PsL also has an outstanding
                          catalog for the Macintosh.